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Introduction 



If you are a .NET programmer working with JavaScript, the 
emerging TypeScript language will be of great interest. 
TypeScript introduces optional static typing and class-based 
object orientation with the intention of making scalable 
high-performance programs that run in the browser or on 
the server. 

Many of the features in the first version of TypeScript are 
inspired by the ECMAScript 6 specification, which means 
they will eventually be available in vanilla JavaScript. For 
these, TypeScript gives early access to language features that 
won't be available in all browsers for some time. On top of 
these, recent versions of the TypeScript language 
specification have added features that may never be natively 
supported, such as generics. 

TypeScript code is compiled into plain JavaScript, which 
means it can run in any web browser or on a server running 
technology such as Node.js. The compilation process 
performs transformations from TypeScript into idiomatic 
JavaScript and erases annotations and interfaces intended 
for compile-time checking. The process of removing type 
information at compile time is termed type erasure. 



6 



Type Erasure 

var name: string = "Steve Fenton"; 

var name = "Steve Fenton"; 

The TypeScript language was created by Anders Hejlsberg 
and a team of developers at Microsoft and is released under 
an Apache 2 open source license. The preview was released 
on 1st October 2012 and was labelled version 0.8. The 
current version of TypeScript, version 0.9, contains some 
key changes including the introduction of generics. 

The latest version of the TypeScript compiler is written in 
TypeScript and the compilation process can run in a 
browser. Typically, the TypeScript compiler runs within 
Node.js as this allows the compiler to read and write files to 
disk. 

This book is aimed at .NET programmers and explains key 
concepts as well as similarities and differences between 
TypeScript and C#. There is a quick start guide in the first 
chapter that introduces the syntax. The later chapters 
include deep dives into the type system, memory 
management, events and exceptions. 
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You can follow the project on Codeplex to keep up to date 
with changes, join in the discussion on the language preview 
and file any bugs you find while using TypeScript. 

http://typescript.codeplex.com/ 
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Compiling or Transpiling 



Despite the fact the term "transpiling" has been around 
since last century, there is some confusion about what it 
means and what the difference is between transpiling and 
compiling. 

Transpilation is actually a specific kind of compilation. 
Compiling is the general term for taking source code written 
in one language and transforming into another, whereas 
transpiling is a specific term for taking source code written 
in one language and transforming it into another language 
with a similar level of abstraction. 

When you compile C#, your method bodies are transformed 
by the compiler into IL. This cannot be called transpiling 
because the two languages are very different levels of 
abstraction. When you compile TypeScript, it is transformed 
by the compiler into JavaScript. These are very similar levels 
of abstraction, so this is called transpiling. 

Both compilers and transpilers can optimise the code as part 
of the process. 

Other common combinations that can be dubbed as 
transpiling include C++ to C, CoffeeScript to JavaScript, Dart 
to JavaScript and PHP to C++. 
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Throughout this book, I will use the general term, 
compilation, rather than the specific term, transpilation. If I 
do use the specific name you'll understand the difference. 
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Language Features 

This section will quickly introduce the key TypeScript 
syntax used to supply explicit type annotations, classes and 
interfaces. Although class-based object-orientation will be 
familiar to most C# programmers, TypeScript is not based 
on C#; it draws inspiration from many different languages. 
This quick start is not intended to be exhaustive, but 
supplies the information you'll need to know before we 
compare TypeScript to C#. 

TypeScript is a statically typed language and will check type 
compatibility at compile time. This improves the 
programming experience by ensuring type-safety and by 
supplying more relevant auto-completion at design time. If 
you have used Visual Studio to edit JavaScript, you will have 
noticed the auto-completion is not very intelligent. This is 
because a variable in JavaScript does not have a fixed type. 
In contrast, using TypeScript offers a highly productive auto- 
complete system because it has intimate knowledge of types. 

TypeScript Files 

TypeScript files have a '.ts' file extension. To add support for 
TypeScript to Visual Studio 2012, you can download the 
extension from: 

http://www.typescriptlang.org/ 
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You can also try most examples in the TypeScript 
Playground: 

http://www.typescriptlang.org/Playground/ 

Your program will be made up of a collection of TypeScript 
files that contain your classes, grouped into modules. 
Modules are similar to C# namespaces and can be used to 
group related classes together. At runtime, your JavaScript 
files can be added to web pages using standard script tags, 
or loaded on-demand using a module loader, which will add 
scripts to your web page as they are needed. When running 
JavaScript on a server, NodeJS has a built-in module loader. 

The method of referencing your dependencies differs based 
on whether you are using a module loader. If you are not 
using a module loader you specify your dependencies using 
a reference comment: 

/// <reference path="Dependency .ts" /> 
var example = new Dependency .MyClass( ) ; 

To load a dependency using a module loader in the browser 
(such as RequireJS) or from a NodeJS program, you use the 
import statement: 

import dependency = module( 'Dependency' )j 
var example = new dependency .MyClass( ) ; 
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Unlike the reference comment, the import statement is 
converted into JavaScript code by the compiler. There are 
two styles of modules that can be targeted - CommonJS 
(RequireJS uses CommonJS) or AMD (NodeJS uses AMD). 
You can switch between these using Visual Studio settings, 
or by passing a module switch to the TypeScript compiler. 
Here is an example of the compiled JavaScript for CommonJS 
and AMD style modules: 

var dependency = require("./CommonDSDependency"); 

define( [ "require" , "exports", 'AmdDependency ' ] , function 

(require, exports, dependency ) { 

var dependency = dependency ; 

} ) 

You will notice the compiler may use single or double 
quotes, this makes no material difference to your JavaScript 
code. 

Using CommonJS with RequireJS causes modules to be 
loaded on demand, rather than all up front. This may 
increase the speed of the initial page load, but may also slow 
down the program at runtime. 

Using AMD on NodeJS the performance benefits are less of a 
concern than code organisation as the files are all local, 
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which means there is no network cost as there is when 
sending JavaScript to a browser. 

Types 

TypeScript contains primitive types of string, number, 
boolean, null and undefined. There is no distinction in 
TypeScript between integers and floating-point numbers 
because JavaScript does not define different numerical types 
and it would not be efficient (or even possible in many 
cases) for the TypeScript compiler to enforce integer values. 
For situations where a dynamic type is desired, TypeScript 
has a type named any. This is analogous to the C# dynamic 
keyword. 

It is possible to declare an array type by appending square 
brackets to a type name, for example string[ ]. 

You can also define your own types, which I'll return to in 
the section on classes. 

Type Inference 

When you write JavaScript inside of a TypeScript file, the 
compiler will automatically infer types in many scenarios. 
Although the following example is plain JavaScript, you can 
hover over the variable names in Visual Studio or the 
TypeScript Playground to see the variables are typed 
string, number and boolean respectively. 
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van myString = 'A String'; 
var myNumber = 1; 
van myBoolean = true; 

The compiler is able to infer type information even for 
complex types. In this example, the structure of the variable 
is all determined by the compiler, so no type annotations are 
needed to gain the benefits of static typing. 

var example = { 

name: 'Example', 
id: S, 

collection: ['a', 'b'., 'c'] 

} 

When you type "example." into the editor, you will get auto- 
completion options of "name", "id" and "collection" - 
these are the only valid options for the example variable. If 
you type "example . collection . " in the editor, you will 
see options relevant to an array of string objects, because 
TypeScript has worked out the type information. 

Type inference does have its limitations. It can only infer the 
type where the assignment is part of the variable 
declaration, so if you declare a variable and assign it later in 
your code (even on the next line) the type will not be 
automatically inferred. 

var unknown; 

unknown = 'A String'; 
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In this case, the unknown variable will have the special type 
named "any". A variable of this type is treated as a dynamic 
type and type-safety is not guaranteed. 

Type Annotations 

In situations where the TypeScript compiler cannot infer the 
types, or where you want to make your intentions explicit, 
you can supply a type annotation. Unlike C#, where the type 
appears before the variable name, the type annotation in 
TypeScript appears after the variable name, and is separated 
from the name by a colon. This style helps to indicate that 
the types are optional. 

Type annotations can be used to type variables, method 
parameters, return values and interfaces. 

Here are our example variables once again, but with the type 
annotations to explicitly type them: 

var myString: string = 'A String'; 

var myNumber: number = 1; 

var myBoolean: boolean = true; 

var example: { 
name: string; 
id: number; 
collection: stringf]; 

} = { 

name: 'Example', 
id: 5, 

collection: ['a', 'b', 'c'] 

} 

var unknown: any; 
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unknown = 'A String'; 



Modules, Classes and Interfaces 

TypeScript modules are used for the purposes of code 
organisation and are similar to namespaces in C#. A module 
can contain many classes and interfaces, which are either 
private to the module, or exported - which makes them 
public. 

TypeScript classes are very similar to C# classes; in fact one 
of the attractions of TypeScript is that it hides JavaScript's 
prototype-based object system with the more familiar class- 
based system. You can extend another class, or implement 
multiple interfaces, add a constructor and expose properties 
and methods. 

The properties and methods you add to your class can use 
either the public or private keyword to modify their 
visibility. These can also be used to mark constructor 
parameters. When you use an access modifier against 
constructor parameters, the arguments passed to the 
constructor are automatically mapped to similarly named 
properties on the class. This point cannot be overstated - 
manually mapping constructor parameters to public or 
private fields is a total waste when TypeScript can do it for 
you. All you need to do is add the access modifier to the 
parameter definition. 
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module Shapes { 

export interface IPoint { 
getDist(): number; 

} 

export class Point implements IPoint { 

constructor(public x: number, public y: number) { } 

getDist() { 

return Math . sqrt(this .x * this.x + this.y * 

this.y); 

} 

static origin = new Point(0, 0); 

} 

} 

var point = new Shapes . Point(50, 243); 
var dist = point. getDistQ; 



The export keyword in this example makes the class and 
interface visible outside of the module. There is more on this 
in the chapter dedicated to access modifiers. To implement 
the interface use the implements keyword, rather than the 
familiar colon syntax from C#. To inherit from a class, you 
use the extends keyword. 

module Animals { 

export class Animal { 

constructor(public animalName) { } 

move() { 

return this. animalName + ' the animal moves'; 

} 

} 

export class Snake extends Animal { 
constructor(animalName) { 
super (animalName) ; 
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} 



} 



} 



move() { 

return this . animalName + 
' the snake slithers'; 

} 



export class Cat extends Animal { 
constructor(animalName) { 
super (animalName) ; 

} 

move() { 

return this . animalName + 

' the cat cannot be bothered to move'; 

} 



var slippy = new Animals. Snake( 'Slippy' ); 
alert ( slippy . move ( ) ) ; 



When you extend a class, you can call methods on the base 
class using the super keyword. To access properties, you 
use the this keyword. You are not forced to override any 
methods on the base class, but if you have a constructor you 
must call the constructor on the base class. If you forget to 
do this the compiler will remind you with a compilation 
error. 

A module name can contain periods and you can extend 
modules throughout your program. You need to balance the 
value of long module names in TypeScript because there is 
no concept of using statements as there is in C# to list your 
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dependencies, which means you need to use the full module 
names in your code. 



module Program. Utilities. Logging { 
export class Console { 

log(message: string): void { 

if (typeof console !== 'undefined') { 
console . log (message) ; 

} 

} 

} 

} 

var logger = new Program. Utilities. Logging. Console(); 
logger. log( 'Test message.'); 



Functions 

Optional, Default and Rest Parameters 

A method in TypeScript can contain optional, default and 
rest parameters, which are all available in C# and work in 
practically the same way. The syntax for declaring each of 
these is shown below. 

To mark a parameter as optional, append a question mark to 
the parameter name. Optional parameters must be ordered 
after non-optional parameters. 

module Parameters { 

export class Example { 

optionalParameter(name? : string) { 
return name; 
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} 

} 

} 



To add a default value to a parameter, append the value 
after the type annotation. As I'll explain at the end of this 
section, the value does not have to be a compile-time 
constant. 



module Parameters { 

export class Example { 

def aultParameter(name : string = 'Default') { 
return name; 

} 

} 



Rest parameters allow calling code to specify zero or more 
instances of the specified type. To specify a rest parameter, 
prefix the name with three periods. Rest parameters must 
appear last in the method signature. 



module Parameters { 

export class Example { 

restParameter( . . . name : string[]) { 
return name .toString( ) ; 

} 

} 

} 



A common example of this in C# is the string. Format 
method, which accepts arguments containing a format string 
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and any number of arguments, which are used to replace 
tokens in this format string. The following example shows 
the method signature for a TypeScript implementation of 
string. Format: 

module System { 

export class String { 

static format(formatString: string, ...args: any[]) { 
// ... 

} 

} 

} 

System. String. format( 'My {0}{1} format example', 1, 'st')j 

Working with TypeScript isn't the same as working with 
JavaScript, C#, Java or any other language TypeScript has 
drawn inspiration from. This has good and bad aspects. On 
the plus side, you might find some features that you couldn't 
do elsewhere, but it means you have to learn some new 
tricks no matter what your background. 

In C# you can have default parameters, but they must be a 
compile-time constant. For example it can be "Whatever", 
but it can't be string. Empty. This isn't usually a problem in 
C#, but wouldn't it be nice if you could have more flexibility? 
In TypeScript, you use data from the instance, or from a 
method call, or from pretty much anywhere you like. Here is 
a quick example: 
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findLastIndex(predicate : (T) => boolean, 

index: number = this . length) : number { 
for (var i = index; i > -1; i--) { 
if (predicate(this.list[i])) { 
return i; 

} 

} 

return -1; 



This example is taken from a TypeScript implementation of 
List<T>. The important bit is the second parameter, which 
has a default value of this . length. This is not a compile- 
time constant, but it is allowed in TypeScript. You could use 
any property or method on the class, even properties and 
methods on a different class, or a static method! In fact, any 
of the following are allowed and a whole lot more: 

(index: number = this. length) 

(index: number = this.someMethod()) 

(index: number = this . someDependency . someMethod( ) ) 

(index: number = StaticClass.someMethod()) 

The reason this is allowable in TypeScript is because the 
default parameter is converted into an in -method check, 
which means the code runs inside the curly-braces at 
runtime. The check inspects the argument that has been 
passed and makes the call to get the default value if needed. 
Check out the first line of the transpiled JavaScript. 
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List . prototype . findLastlndex = function (predicate, index) 
{ 

if (typeof index === "undefined") { 
index = this . length; 

} 

for(var i = index; i > -1; i--) { 
if (predicate(this.list[i])) { 
return i; 

} 

} 

return -1; 

}; 

This means you get the syntactical sugar of default 
parameters with the in-method functionality of a manually 
written check. 

Overloads 

Overloaded methods in TypeScript differ from C# because 
they only have a single implementation with multiple 
signatures. In C# each signature would have its own 
implementation. In TypeScript, the final signature 
(sometimes called the "implementation signature") is not 
callable except via one of the overloads preceeding it. In the 
example below, you can call the method with a string or a 
number only - even though the implementation signature 
accepts any type. 

module Overloads { 
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export class Example { 

overloadedMethod(input : string); 
overloadedMethod(input : number); 
overloadedMethod(input : any) { 
return input .toString( ) ; 

} 

} 

} 

var example = new Overloads. Example(); 
example . over loadedMet hod ( 1) ; 
example. overloadedMethod( 'A String' ); 



Enumerations 

TypeScript enumerations are very similar to C# 
enumerations. In both cases you can optionally allocate the 
values to the enum. 



enum States { 
Solid, 
Liquid, 
Gas 

} 

enum Sizes { 
Small = 3, 
Medium = 5, 
Large = 8 

} 



The JavaScript output for the States enumeration is shown 
below. 



var States; 
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(function (States) { 

States. _map = []; 

States ._map[0] = "Solid"; 

States. Solid = 0; 

States ._map[l] = "Liquid"; 

States . Liquid = 1; 

States ._map[2] = "Gas"; 

States. Gas = 2; 
})(States | | (States = {})); 



The interesting part of this declaration is that it shows it 
technically possible to obtain the name as well as the value 
of the enumeration. In the JavaScript you can see 
States._map is an array of names matching the values. Oddly, 
to get the names via TypeScript you need to make the 
enumeration appear dynamic, as shown below. 

var state = States . Liquid; 

alert( (<any>States) ._map[state] ); // "Liquid" 



Generics 

At the time of writing, generics have been newly added to 
TypeScript, but in general they will be familiar to a C# 
programmer - although they are styled after Java's 
implementation of generics. 

module Generics { 

interface IExample<T> { 

getById(id: number): T; 
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} 

class MyClass { 

constructor^ ) { } 

} 

class Example implements IExample<MyClass> { 
getById(id : number) { 

return new MyClass(); 

} 

} 



Type Constraints 

In C# you can add type constraints using the where 
keyword, but in TypeScriptthe extends keyword is used 
within the angle-brackets to specify a type constraint; this 
has the same effect as C#'s where condition. In the example 
below, the IExample interface accepts a type parameter only 
if the type is a class that implements the IMylnterf ace 
interface. The extends keyword in a type constraint is the 
same whether you are ensuring a type implements an 
interface or extends a class. 

module GenericConstraints { 

export interface IMyInterface{ 
name: string; 

} 

export interface IExample<T extends IMylnterf ace> { 
getById(id: number): T; 

} 

export class MyClass implements IMylnterf ace{ 
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public name: string; 



constructor^ ) { 

this. name = 'A string'; 

} 

} 

export class Example implements IExample<MyClass> { 
getById(id: number) { 

return new MyClass(); 

} 

} 



If you need to specify multiple type constraints, you can 
create a super-interface describing the structure of the 
constraint. For example if you wanted to specify a type 
constraint stating the type must extend both ClassOne and 
ClassTwo, you could create an interface that describes this. 

interface ISuperlnterf ace extends ClassOne, ClassTwo { 
} 

export interface IExample<T extends ISuperlnterf ace> { 
getById(id: number): T; 

} 

Additionally, you can specify a type constraint that is also 
generic. 

interface INested<T extends IExample<T>> { 
} 
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Structural Typing 



C# has a nominative type system, whereby the type of an 
object is determined using explicit declarations. If two types 
had identical structures, they would not be considered the 
same type. TypeScript is structurally typed; any types with 
compatible structures are considered the same type 

Here is an example in C#. ClassA and ClassB are not 
compatible types. To make these types compatible they 
would need explicit inheritance or an interface to describe 
their commonality. 



public class ClassA 
{ 

public string SomeMethod( string name) 
{ 

return name; 

} 

} 

public class ClassB 
{ 

public string SomeMethod( string name) 
{ 

return name; 

} 

} 



In TypeScript, all of the following are considered to be the 
same type. You can prove this by assigning an instance of 
ClassB, or ExampleC to a variable of type ClassA. Each of 
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these types has a method with the same signature and 
return type, so they are considered the same type. 



class ClassA { 

SomeMethod(name : string) { 
return name; 

} 

} 

class ClassB { 

SomeMethod(name : string) { 
return 'Arbitrary value'; 

} 

} 

var ExampleC = function () { 

this.SomeMethod = function (name: string) { 
return name; 

} 

} 

var proof: ClassA = new ExampleCQ; 



The structural type system in TypeScript means compatible 
types can be used without verbose type information being 
constructed. This gives the programmer the choice of when 
to be explicit and when to take advantage of type inference. 
This is one of TypeScript' s most powerful features, but it can 
be confusing if you are familiar with other type systems. 
Using type inference and structural typing is very similar to 
C# anonymous types. The TypeScript compiler will create an 
anonymous type and re-use it where it finds other instances 
with the same structure. 
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var objA = { firstName: ' Steve ' , lastName: 'Fenton' }; 
var objB = { firstName: 'Mark', lastName: 'Dones' }; 
var objC = { firstName: ' Dames ' , lastName: 'Liang' }; 

// { firstName: string; lastName: string; }[] 
var arrayA = [objA, objB, objC]; 

In this example, an anonymous type is created with the 
following definition: 

{ 

firstName: string; 
lastName: string; 

} 

Not only does this allow development tools to supply 
appropriate auto-completion, it also means the type will be 
checked by the compiler. If you try to assign a number to the 
firstName property on one of these objects, the compiler 
will generate an error. The compiler also infers the correct 
type for the array of anonymous types. If you add types with 
different definitions, TypeScript will attempt to create an 
array of the most common type. If it is not able to find 
commonality, it will create an array using the any type. In 
the following example, the common type includes the 
firstName property, but not the lastName property 
because the lastName property is not common to all of the 
types. 
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var objA = { firstName: 'Steve', lastName: 'Fenton' }; 
var objB = { firstName: 'Nick' }; 

// { firstName: string; }[] 
var arrayB = [objA, objB]; 

These inferred, or anonymous, types are enforced just as 
strongly as explicit types. You can't later attempt to add a 
property that wasn't declared up front, because the 
anonymous type generated by the compiler does not define 
properties or methods that aren't part of the original 
structure. 

var objD = { firstName: 'Nick' }; 

// Not allowed 

//objD. lastName = 'Liang'; 
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Access Modifiers 



TypeScript has a small set of access modifiers that let you 
hide implementation details from the rest of your 
TypeScript program. It is important to note this is a compile - 
time feature that doesn't prevent access at runtime. When 
you write a module, everything inside the module is private 
unless you explicitly make it available using the export 
keyword. If you omit the export keyword, you can only 
create and use instances within the module. If you try to 
return an instance of a private class from a public method, 
the compiler will issue an error. 

Inside a class, things are the other way around; methods and 
properties are public by default, so you need to explicitly 
hide them with the private modifier. You can optionally 
use the public modifier to make your intentions explicit if 
you wish. 



module AccessModifiers { 

// A private class (no export keyword) 
class PrivateClass { 
//... 

} 

// A public class 

export class PublicClass { 

private privateProperty : string = 'Private'; 

publicProperty : string = 'Public'; 

implicitPublicMethodQ { 
return 'Public'; 
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} 



public explicitPublicMethod() { 
return 'Public'; 

} 

private privateMethod( ) { 
return 'Private'; 

} 

} 

} 

var publicClass = new AccessModifiers.PublicClass(); 
alert(publicClass . publicProperty) ; 
// Not allowed 

// alert ( publicClas s .privateProperty) ; 
// Not allowed 

//var privateClass = new AccessModif iers . PrivateClass( ) ; 



There are no internal or protected modifiers in 
TypeScript, so you can't make a method or property 
accessible to a sub-class without also making it publically 
accessible. 



module InheritanceAccess { 
class BaseClass { 

publicProperty = 'Public'; 

private privateProperty = 'Private'; 

} 

class MyClass extends BaseClass { 
myMethod() { 

super .publicProperty = 'Public'; 

// Not allowed 

//super. privateProperty = 'Private'; 

} 
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Memory Management 



When you run a TypeScript program, it is the compiled 
JavaScript being executed. JavaScript behaves similarly to 
.NET in terms of memory management; memory is allocated 
when objects are created and freed when the objects are not 
used any more. The major difference in the JavaScript world 
is each browser or server technology may have a different 
implementation of a garbage collector, which means the 
memory profile of your program may be less predictable 
than it would be if you wrote it in C#. 

For example, older web browsers may use a reference- 
counting garbage collector, freeing memory when the 
number of references to an object reaches zero. This is a 
very fast way to collect garbage as the memory can be freed 
as soon as the reference count reaches zero. However, if a 
circular reference is created between two or more objects, 
none of these objects will ever be garbage collected because 
their count will never reach zero. 

This problem is largely solved in modern web browsers, 
which use a mark-and-sweep algorithm to detect all 
reachable objects and garbage-collect the objects that are 
not reachable. Although this style of garbage collection can 
take longer, it is less likely to result in memory leaks. 
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Reference Counting 



Object 


Reference Count 


Object 1 


1 


Object 2 


3 


Object 3 


0 



In this reference counting example, objects are garbage 
collected as soon as the reference count reaches zero. If the 
count is greater than zero the object survives the collection. 
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Mark-and-Sweep 





[ Objects 




Object 9 



In this mark-and-sweep example, objects that are reachable 
survive the garbage collection, but objects that are not 
reachable are collected. 

Despite the differences between JavaScript and C# garbage 
collection, the subject is largely academic and you do not 
need to explicitly write code to help the garbage collector; it 
will automatically run when memory is needed. 



38 



Releasing Resources 

In TypeScript, you are more likely to encounter unmanaged 
resources when using Node.js than when running inside of a 
browser. Most browser APIs that interact with hardware are 
designed to accept a method you supply as a callback, so you 
never hold a reference to the unmanaged resource in your 
program. For example, if you wanted to use the proximity 
API, which detects when an object is near the sensor, you 
would use the following code: 

var sensorChange = function (proximity) { 
var proximity = proximity. near ? 

'Near' : 'Far'; 
alert (proximity); 

} 

window. add E vent Listener ( ' user proximity ' , 
sensorChange, true); 

As you can see in this example, although you can subscribe 
to an event that fires based on the proximity sensor, you do 
not hold a reference to the sensor that needs to be released. 

In Node.js, however, you may find you have references to 
unmanaged resources, in which case you should ensure you 
release those resources to avoid memory leaks. To do this 
you can use try-finally blocks, with the resources being 
released in the finally block. The finally block is 
guaranteed to run regardless of any errors in the try block. 
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var file = File.open(); 
try { 

file.write( ' Example' )j 
} finally { 

file.close(); 

} 
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Exceptions 



You can raise an exception in TypeScript using the throw 
keyword. In JavaScript you can follow the throw statement 
with any type, although typically strings are used to supply 
an error message. In TypeScript it is more usual to throw an 
Error object. 

throw (new Error( 'An error has occurred.')); 

To create a custom exception, a class can implement the 
Error interface. This allows you to name your own error 
types. Custom exceptions can be used if you need to perform 
specific actions on a particular exception or if you want to 
test the type of exception inside a catch block. 

class ExampleError implements Error { 

public name: string = 'ExampleError'; 
constructor(public message: string) { 
} 

} 

To handle an exception, you can use a try- catch block. 
This is largely similar to try- catch blocks in C# except you 
cannot catch specific exception classes with multiple catch 
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blocks. Instead, you can test the exception name inside your 
catch block. 



try { 

if (true) { 

throw (new ExampleError( ' An error has occurred.')); 

} 

} catch (error) { 

switch (error. name) { 
case ' ExampleError ' : 

alert (error .message); 
break; 
default: 

throw error; 

} 

} 



If you need to guarantee clean-up, you can use a finally 
block to perform clean up. Code inside the finally block 
will execute before subsequent code, even if an exception 
occurs. More information on the finally block is available 
in the Memory Management chapter. 
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Arrays 



From TypeScript 0.9 onwards, arrays are generic and have 
precise typing for their contents. To take advantage of this, 
you can supply a type annotation with square brackets 
appended. TypeScript checks the types of items being added 
to the array and will infer the type for items retrieved from 
the array. 



class MyType { 

constructor(public name: string) { 
} 

} 

var simpleTypedArray : stringf] = []; 
var complexTypedArray : MyType [] = []; 

//simpleTypedArray. push(2); // not allowed 

simpleTypedArray. push( 'Some String' ); 

var arrayltem = simpleTypedArray [0] ; // string 



Because TypeScript doesn't currently include a framework 
class library, only definitions for built-in JavaScript 
functions and browser interfaces, there are no classes or 
interfaces for generic lists like those in C#. This doesn't 
prevent you from defining your own. Here is an example of a 
generic list class, which doesn't implement all of the 
methods you'll be familiar with, but demonstrates the key 
features you need to implement the class. 



44 



class List<T> { 

private list: T[] = []; 

constructor(list? : T[]) { 
this. list = list || []; 

} 

get length(): number { 

return this . list . length; 

} 

add(obj: T): void { 

this .list. push( obj); 

} 

addRange( ... items : T[]): void; 
addRange(items : T[]): void; 
addRange(items : T[]): void { 

this. list = this. list. concat(items) ; 

} 

clear() { 

this. list = []; 

} 

contains(obj : T): boolean { 

for (var i = 0; i < this. list. length; i++) { 
if (this.list[i] === obj) { 
return true; 

} 

} 

return false; 

} 

convertAll<TOutput>(converter : (obj: T) => TOutput): 
List<TOutput> { 

var list = new List<TOutput>( ) ; 
for (var i = 0; i < this. list. length; i++) { 
list .add (converter (this . listfi] ) ) ; 

} 

return list; 

} 
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f ind(predicate : (T) => boolean): T { 

for (var i = 0; i < this. list. length; i++) { 
if (predicate(this.list[i])) { 
return this.listfi]; 

} 

} 

return null; 

} 

f indAll(predicate : (T) => boolean): T { 
var results = new List<T>(); 
for (var i = 0; i < this. list. length; i++) { 
if (predicate(this.list[i])) { 
results . add(this . list [i] ) ; 

} 

} 

return results; 

} 

f indlndex(predicate : (T) => boolean, index: number = 0): 
number { 

for (var i = index || 0; i < this. list. length; i++) 

{ 

if (predicate(this.list[i])) { 
return i; 

} 

} 

return -1; 

} 

findLastIndex(predicate : (T) => boolean, index: number = 
this. length) : number { 

for (var i = index; i > -1; i--) { 
if (predicate(this.list[i])) { 
return i; 

} 

} 

return -1; 

} 

forEach(action : (obj: T) => any): void { 

for (var i = 0; i < this. list. length; i++) { 
action (this. list [i]); 
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} 

} 



getltem( index: number): T { 
if (this. list [index]) { 

return this.listfindex]; 

} 

} 

setltem(index: number, obj: T): void { 
this .listfindex] = obj; 

} 

toArray(): T[] { 

var arr: T[] = []; 

for (var i = 0; i < this. list. length; i++) { 
arr. push (this. list [i]); 

} 

return arr; 



trueForAll(predicate: (T) => boolean): boolean { 
var results = new List<T>(); 
for (var i = 0; i < this. list. length; i++) { 
if ( !predicate(this.list[i])) { 
return false; 

} 

} 

return true; 

} 

} 



The List class demonstrates many of TypeScript's language 
features and supplies a reasonable equivalent to the .NET 
framework class library generic List. Here are some 
examples using the List class: 

var list = new List<string>( [ 'One ' , 'Two']); 
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alert(list. length. toString())j // 2 
alert ( list .getltem(l) ) ; // 'Two' 

list .addRange( [ ' Three ' , ' Four ' ] ) ; 

alert(list. length. toString()); // 4 

// Example using rest parameters overload 
list . addRange( 1 Five 1 , 'Six'); 
// Example using the array overload 
list .addRange( [ ' Seven ' , ' Eight ' ] ) ; 

var stringList = new List<string>( [ ' 12 ' , '12', '3'])j 

stringList .forEach(f unction (str: string): void { 
alert(str) ; 

} ); 
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Dates 



Dates in TypeScript are based on the JavaScript Date object, 
which are represented by the number of milliseconds since 
1 January 1970 00:00:00 UTC. 

The Date object accepts arguments from least to greatest 
precision. 

// Year, Month, Day 

var myDate = new Date(2012, 05, 12); 

// Yean, Month, Day, Hours, Minutes, Seconds, Milliseconds 
var myDateTime = new Date(2012, 05, 12, 15, 33, 10, 100); 

You can also construct a date using a string in either RFC or 
ISO format or using a numeric value representing the 
number of milliseconds (once again, since 1 January 1970 
00:00:00 UTC). 

var dateFromRfc = new Date('12 Dec 2011 00:50:00 +0000'); 
var dateFromlso = new Date( '2011-01-31T18:30:00' ); 
var dateFromNumber = new Date(1369251402587); 
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Now 



You can access the current date and time using the 
Date . now( ) method. As this returns the value in 
milliseconds, you will need to pass this value into a new 
Date object if you want to perform date operations. 

var now = new Date(Date . now( ) ) ; 

Date Methods 

Once you have a Date object, you can access the individual 
date components using the methods built into the Date 
object. There are two sets of methods; one gives access to 
the date components in local time, the other returns the UTC 
values of the date components. In the example below, you'll 
note we add one to the month, because the value returned 
from getMonth and getUTCMonth is zero-based, so January 
is 0, February is 1 and so on. 

var yean = now. getUTCFullYear ( ) ; 
var month = now. getUTCMonth () + 1; 
var date = now. getUTCDate( ) ; 

alert(year + ' ' + month + ' ' + date); 
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The date components are available for year, month, day-of- 
month (date), hours, minutes, seconds and milliseconds. All 
of these values are available in local and UTC flavours. 

You can also get the day of the week using getDay or 
getUTCDay, which again is zero based, with Sunday being 0, 
Monday being 1 and so on. 

You can also take advantage of methods that display the 
Date object in various formats. The following examples are 
based on a date of 3 rd June 2013 at 9:25pm UTC. The locale 
strings are based on the user's browser, or the server 
running Node.js. 



alert ( now. toDat eSt r ing ( ) ) ; 
// Mon Dun 03 2013 

alert ( now. toISOSt ring ( ) ) ; 
// 2013-06-03T21:25:05.531Z 

alert(now.toDSON()); 

// 2013-06-03T21:25:05.531Z 

alert ( now. toLocaleDateStr ing ( ) ) ; 
// 03 Dune 2013 

alert ( now. toLocaleStr ing ( ) ) ; 
// 03 Dune 2013 22:25:05 

alert ( now. toLocaleTimeStr ing ( ) ) ; 
// 22:25:05 
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Events 



Events in TypeScript come from the Document Object Model 
API, which has a standard set of built in events for mouse 
and keyboard interactions and for object and form events. 
The following list of events is not exhaustive, but supplies 
some indication of the kind of built-in events you can 
subscribe to. 



Mouse Events 



Event 


Triggered when... 


onblur 


Focus moves away from the target 
element. 


onclick 


A mouse click is detected on the target 
element. 


ondblclick 


A double mouse click is detected on 
the target element. 


onfocus 


Focus moves to the target element. 


onmousedown 


A mouse button is pushed down on the 
target element. 


onmousemove 


The mouse pointer moves within the 
target element. 
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onmouseover 


The mouse pointer is moved over the 
target element. 


onmouseout 


The mouse pointer is moved away 
from the target element. 


onmouseup 


A mouse button is released on the 
target element. 



Keyboard Events 



Event 


Triggered when... 


onkeydown 


A key is pushed down within a target 
element. 


onkeypress 


A key is pressed within a target element. 


onkeyup 


A key is released within a target element. 



Object Events 



Event 


Triggered when... 


onload 


An object is loaded (i.e., a document or 
image). 


onresize 


An object is resized. 


onscroll 


A document is scrolled. 
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onunload 


A document is closed. 



Form Events 



Event 


Triggered when... 


onchange 


The contents of the target input element are 
changed. 


onreset 


A form is reset (cleared). 


onsubmit 


A form is submitted. 



Custom Events 



The same mechanism can be used to dispatch and listen for 
custom events in your TypeScript program. Any given event 
can have multiple listeners and multiple dispatchers. 

Here is an example of a class that listens for a custom event: 



class ListenerOne { 
constructor () { 



document . addEventListener ( ' myCustomEvent ' , 
this. event Listener) ; 



eventListener(e: Event) { 

alert(' Event caught by ListenerOne'); 

} 
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} 



The class below dispatches a custom event: 

export class TriggeringClass { 
triggerEvent( ) { 

var evt = document . createEvent( ' Event ') ; 
evt . init Event ( 1 myCustoinE vent 1 , true, true); 
document . dispatch Event (evt) ; 

} 

} 

Although this method is due to be replaced, this is the 
current cross-browser way to register and trigger events. 

Running Order 

Events run in the order they are registered. This is an 
important consideration because event handlers run in 
sequence, not concurrently. 

If you register two event listeners and the first one takes five 
seconds to run, the second event handler will not be called 
until the first has completed. If the first fails, the second 
event handler will still be called. 

You can prevent an event listener from blocking other event 
listeners by calling long-running actions in a zero- 
millisecond timeout. 
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eventListener(e : Event) { 

window. setTimeout(longRunningMethod J 0) ; 

} 

This allows other events to execute before the long running 
method and avoids the need to explicitly order the event 
handlers when you know one may be long running. 
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Framework 



TypeScript comes bundled with definitions for the objects 
and methods you would expect to find in a browser. Because 
web standards are constantly evolving you may discover the 
need to extend these definitions to include something new 
that hasn't made it into the standard library. You can view 
the standard library file on your computer by browsing to 
the TypeScript SDK in your Program Files directory, for 
example: 

C:\Progr-am Files (x86) \Microsoft 
SDKs\TypeScript\lib.d.ts. 

You should never edit this file Most of the library definitions 
use interfaces to declare the types and TypeScript interfaces 
are open, which means you can continue their definition in 
multiple files. 

For example, the following is the current definition of 
Client Rect List in the TypeScript library file. 

interface ClientRectList { 
length: number; 

item(index: number): ClientRect; 
[index: number]: ClientRect; 

} 
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If a new property named isOrdered was added to the 
specification of ClientRectList and you needed to use 
this property, you could simply add the following interface 
extension to your program to make it available immediately. 

interface ClientRectList { 
isOrdered: boolean; 

} 

When it makes its way into the standard library, you'll be 
reminded to remove this extension with a build error about 
the duplicate declaration. 

When you create instances of a ClientRectList you will 
now be able to access items by index, call the item method, 
obtain the length property and obtain the new isOrdered 
property. 

Apart from these definitions, there is no additional 
framework for TypeScript at the current time. I touched on 
this in previous chapters, but also demonstrated it is 
possible to recreate practically any of the classes you know 
and love from C#, because TypeScript has a rich set of 
language features. 

You also have access to all of the existing JavaScript 
frameworks, such as j Query, Knockout, Angular and 
hundreds of others. Because they are written in pure 
JavaScript, you won't get a rich development experience 
with these frameworks unless you have a matching 

58 



definition file - luckily there is a project dedicated to 
supplying declarations for all of the major JavaScript 
frameworks. The Definitely Typed project can be found on 
GitHub. 

https://github.com/borisyankov/DefinitelyTyped 

If you needed to use equivalents to ICloneable or 
INotif yPropertyChanged from C#, you can transfer the 
patterns to TypeScript. 
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Creating Definitions 



There are occasions where you will want to consume a 
JavaScript library, framework or toolkit in your TypeScript 
program. Without some help, the TypeScript compiler will 
struggle to understand this external code, for which it has no 
type information. 

Dynamic Declarations 

The simplest way to use external code in your program is to 
declare a variable with the any keyword. The TypeScript 
compiler will now allow any method or property calls 
against this dynamic object. This takes you past the 
compiler but doesn't give you rich auto-completion or type 
checking. 

declare van $: any; 
$ . anythingYouLike ( ) ; 

The special keyword in this example is the declare 
keyword. This tells TypeScript the code is external and, as a 
result, this declaration will only be used by the compiler and 
development tools. The entire line will be erased when the 
code is compiled to JavaScript. 
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Type Declarations 

To get a better development experience with the external 
code, you can supply a more comprehensive declaration. 
You can declare variables, modules, classes and functions in 
order to define the type information for the external code. 
You may start by declaring the parts you intend to use 
immediately and extend the declarations on an as-needed 
basis. The declare keyword only needs to appear at the 
start of the declaration. 

declare module ExternalToolKit { 
export class ExternalClass { 

static externalProperty : bool; 

static run(iterations : number, text: string): void; 

} 

} 

ExternalToolKit. ExternalClass. run(5, 'Hello World'); 



You should only declare external code as a class if it can 
genuinely be extended by a TypeScript class. If it cannot be 
extended, it is better to declare it using an interface. 



declare class CanBeExtended { 
run(): string; 

} 

declare var libl: CanBeExtended; 

interface CannotBeExtended { 
run(): string; 

} 
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declare van lib2: CannotBeExtended; 



The only difference between these two styles of declaration 
is whether the TypeScript code can extend the external code. 
In both cases, the type information is erased from the 
compiled JavaScript. 

Very often, your declaration will be made up of a series of 
interfaces that build up the bigger picture. You can even 
create interfaces to represent JavaScript code you couldn't 
actually implement in TypeScript. For example, it is perfectly 
acceptable to do this: 

interface AmazingMove { 

(x: number, y: number): void; 
up(distance: number): void; 
down(distance : number): void; 
left(distance : number): void; 
right(distance: number): void; 

} 

interface Amazing { 
move: AmazingMove; 

} 

declare var amazing: Amazing; 
amazing. move(40, 30); 
amazing. move . up (40) ; 

In this example the Amazing interface has a property named 
move, which can be called as a method as well as have 
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nested methods. This is good example of how you might 
declare external code that couldn't actually be written in 
TypeScript in its current form. This makes it possible to 
declare almost anything you might want to use, from j Query 
to Knockout to Angular to RequireJS or even old JavaScript 
code that you have in your program you haven't got around 
to re-writing in TypeScript. 
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Useful Tricks 



Obtaining Runtime Types 

It can be useful to inspect the class name at runtime. In C# 
there are several ways to obtain the type of an object, but in 
TypeScript it is not so obvious. 



class Types { 

static getType(inputClass) { 

var f uncNameRegex = /function (.{1,})\(/; 

var results = (funcNameRegex) .exec((<any> 
inputClass) . constructor . toSt ring ( ) ) ; 

return (results && results . length > 1) ? resultsfl] 

y 

} 

} 

class Example { 
} 

class AnotherClass extends Example { 
} 

var x = new Example(); 

var y = new AnotherClass( ) ; 

alert(Types.getType(x)); // Example 
alert (Types . getType(y) ) ; II AnotherClass 



The static method, get Type, inspects the compiled 
JavaScript function and extracts its name, which will be the 
name of the class in your TypeScript file. 
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The limitation on this technique is you cannot obtain the full 
module path to the class, which means MyModule . Example, 
SomeOtherModule . Example and the unwrapped class 
Example all return the string "Example". 

Extending Native Objects 

The built in declarations for TypeScript describe native 
JavaScript objects and functions. You can view these 
declarations in the lib.d.ts library file. You'll notice most 
of the declarations use interface style declarations. Because 
TypeScript interfaces are open, it is reasonably simple to 
extend the native JavaScript objects. 

For example, the following is a useful JavaScript snippet for 
extending the NodeList object to support the binding of an 
onclick event when using document . querySelectorAll. 

NodeList. prototype. onclick = function (handler) { 
for (var i = 0; i < this. length; i++) { 
this[i] .onclick = handler; 

} 

}; 

document. querySelectorAll( ' .myClass ') .onclick = function () 
{ 

alert(this . innerHTML) ; 

}; 

If you were to add this code to a TypeScript file, the compiler 
would correctly warn you that NodeList object does not 
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have an onclick function. To solve this type checking issue, 
you can simply extend the NodeList interface. 

interface NodeList { 

onclick: (handler: Function) => void; 

} 

This interface declaration can be in any referenced file - you 
don't update the lib . d . t s file (which will be overwritten 
when you upgrade to a new version of TypeScript). This is 
an incredibly powerful feature allowing programmers to use 
the dynamic nature of JavaScript when they want to. 
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